"""
端口检查工具模块
功能：检查端口可用性，防止自动端口切换
参数：主机地址、端口号
返回值：端口是否可用
使用场景：服务启动前的端口验证
"""

import socket
import sys


def check_port_available(host: str, port: int) -> bool:
    """
    检查指定端口是否可用
    参数：
        host: 主机地址 (如 "127.0.0.1")
        port: 端口号 (如 8000)
    返回值：
        True: 端口可用
        False: 端口被占用
    """
    try:
        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
        sock.settimeout(1)
        result = sock.connect_ex((host, port))
        sock.close()
        return result != 0
    except Exception:
        return False


def ensure_port_available(host: str, port: int, service_name: str = "服务") -> None:
    """
    确保端口可用，如果被占用则退出程序
    参数：
        host: 主机地址
        port: 端口号
        service_name: 服务名称（用于错误提示）
    功能：如果端口被占用，显示错误信息并退出
    """
    if not check_port_available(host, port):
        print("=" * 60)
        print(f"❌ {service_name}启动失败：端口 {port} 已被占用！")
        print("=" * 60)
        print("💡 解决方案：")
        print(f"   1. 停止占用端口的服务：")
        print(f"      - Windows: netstat -ano | findstr \":{port}\"")
        print(f"      - Linux/macOS: lsof -i:{port}")
        print(f"   2. 使用端口清理工具：")
        print(f"      - Windows: check-ports.bat clean")
        print(f"      - Linux/macOS: ./check-ports.sh clean")
        print(f"   3. 使用其他端口：")
        print(f"      - python run.py --port {port + 1}")
        print("=" * 60)
        print("🚫 自动端口切换已禁用，请手动解决端口冲突")
        print("=" * 60)
        sys.exit(1)


def get_port_info(host: str, port: int) -> dict:
    """
    获取端口详细信息
    参数：
        host: 主机地址
        port: 端口号
    返回值：包含端口状态信息的字典
    """
    is_available = check_port_available(host, port)
    return {
        "host": host,
        "port": port,
        "available": is_available,
        "status": "可用" if is_available else "被占用",
        "url": f"http://{host}:{port}"
    } 